Data Model: Cloud Demo Infrastructure

Feature: 007-cloud-demo-infra Date: 2026-02-15

Entities

1. HetznerServer

Represents a virtual machine provisioned in Hetzner Cloud.

Attribute	Type	Description	Constraints
name	string	VM hostname	Required, unique, pattern: (mgmt\|login\|compute)[0-9]+
server_type	string	Hetzner instance type	cpx11 or cpx21
image	string	OS image	rocky-9
location	string	Datacenter region	hil (US West Hillsboro)
public_ip	string	IPv4 public address	Nullable (compute nodes have none)
private_ip	string	Private network IP	Required, 10.0.0.0/24 range
ssh_keys	list[string]	SSH key IDs	At least one required
labels	map	Resource metadata	Includes cluster, ttl, created_at

Terraform Resource: hcloud_server

2. HetznerNetwork

Represents the private network connecting all VMs.

Attribute	Type	Description	Constraints
name	string	Network name	demo-network
ip_range	string	CIDR block	10.0.0.0/8

Terraform Resource: hcloud_network

3. HetznerSubnet

Represents a subnet within the private network.

Attribute	Type	Description	Constraints
network_id	string	Parent network	FK to HetznerNetwork
type	string	Subnet type	cloud
network_zone	string	Datacenter zone	us-west
ip_range	string	Subnet CIDR	10.0.0.0/24

Terraform Resource: hcloud_network_subnet

4. HetznerSSHKey

Represents an SSH public key registered with Hetzner.

Attribute	Type	Description	Constraints
name	string	Key identifier	demo-key
public_key	string	SSH public key content	Ed25519 or RSA format

Terraform Resource: hcloud_ssh_key

5. ServerNetworkAttachment

Associates a server with the private network and assigns a private IP.

Attribute	Type	Description	Constraints
server_id	string	Server to attach	FK to HetznerServer
network_id	string	Network to join	FK to HetznerNetwork
ip	string	Assigned private IP	Must be in subnet range

Terraform Resource: hcloud_server_network

6. GeneratedInventory

Represents the Ansible inventory file generated from Terraform outputs.

Attribute	Type	Description	Constraints
path	string	File path	infra/terraform/inventory.yml
groups	map[string, list]	Host groups	mgmt, login, compute, all
host_vars	map	Per-host variables	ansible_host, ansible_user, node_role

Generated by: Terraform local_file resource with templatefile()

Relationships Diagram

┌─────────────────┐
│  HetznerSSHKey  │
└────────┬────────┘
         │ injected into
         ▼
┌─────────────────┐     attached to    ┌─────────────────┐
│  HetznerServer  │◄──────────────────▶│  HetznerNetwork │
│  (mgmt01, etc.) │                    └────────┬────────┘
└────────┬────────┘                             │
         │                                      │ contains
         │ private IP from                      ▼
         │                            ┌─────────────────┐
         └───────────────────────────▶│ HetznerSubnet   │
                                      │ (10.0.0.0/24)   │
                                      └─────────────────┘

┌─────────────────┐
│ HetznerServer   │──────┐
│ outputs (IPs)   │      │ templatefile()
└─────────────────┘      │
                         ▼
                ┌─────────────────┐
                │GeneratedInventory│
                │ (inventory.yml) │
                └─────────────────┘

Node Configuration

Node	Type	RAM	Public IP	Private IP	Slurm Role
mgmt01	cpx21	4GB	Yes	10.0.0.10	controller
login01	cpx11	2GB	Yes	10.0.0.20	submit
compute01	cpx11	2GB	No	10.0.0.31	compute
compute02	cpx11	2GB	No	10.0.0.32	compute

Resource Labels (Tags)

All Hetzner resources are tagged with:

Label	Value	Purpose
cluster	rcd-demo	Identifies demo resources for teardown
ttl	4h	Time-to-live threshold for warnings
created_at	ISO 8601 timestamp	Used for TTL calculations
managed_by	terraform	Indicates IaC management

State Transitions

Cluster Lifecycle

                  ┌─────────────┐
                  │  No Cluster │
                  └──────┬──────┘
                         │ make demo-cloud-up
                         ▼
               ┌─────────────────┐
               │   Provisioning  │
               │ (terraform apply)│
               └────────┬────────┘
                        │ success
                        ▼
               ┌─────────────────┐
               │   Configuring   │
               │ (ansible-playbook)│
               └────────┬────────┘
                        │ success
                        ▼
               ┌─────────────────┐
        ┌─────▶│     Running     │◀─────┐
        │      └────────┬────────┘      │
        │               │               │
        │ TTL warning   │ make demo-    │ run scenarios
        │ displayed     │ cloud-down    │
        │               ▼               │
        │      ┌─────────────────┐      │
        │      │   Destroying    │      │
        │      │(terraform destroy)│    │
        │      └────────┬────────┘      │
        │               │ success       │
        │               ▼               │
        │      ┌─────────────────┐      │
        └──────│  No Cluster     │──────┘
               └─────────────────┘

Validation Rules

1. Cluster uniqueness: Only one cluster can exist at a time (Terraform state non-empty blocks spin-up)
2. SSH key existence: At least one SSH key must be present at ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub
3. Private IP assignment: Each node gets a unique IP in the 10.0.0.0/24 range
4. Public IP assignment: Only mgmt01 and login01 receive public IPs
5. Label consistency: All resources must have cluster=rcd-demo label for teardown identification